home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / libs / libhelp.rea < prev    next >
Text File  |  1996-11-17  |  9KB  |  245 lines
  1. libhelp - a html based help system for osf/motif applications
  2. -------------------------------------------------------------
  3.  
  4.     welcome to libhelp 1.8.1 (Jun 28. 95)
  5.  
  6.     this Readme details compilation steps  for libhelp.  more complete
  7.     information  and documentation on libhelp is  available as part of
  8.     the online  help system it implements.   see section "getting more
  9.     help"  for getting more information.  this is  $Revision: 1.11 $ of
  10.     the Readme file.
  11.  
  12. about
  13. -----
  14.  
  15.     libhelp is a comprehensive hypertext-help-system for OSF/Motif(tm)
  16.     applications which uses    the html widget  from   NCSA Mosaic(tm)
  17.     version 2.4. the help  browser provides hypertext links, different
  18.     fonts, inlined images  and a lot of more  elements  known from www
  19.     (world wide web)     browsers.  it has  a   document   history and
  20.     implements buffer and image cache methods.
  21.  
  22.     libhelp  provides  two interface functions   for  getting help and
  23.     setting resources.  it eases  the task of writing  the application
  24.     help. menu and context  sensitive   help are supported.   Lowlevel
  25.     Motif and X stuff is hidden from the application developer (and of
  26.     course the user too). libhelp works with (at least) ansi-c and c++
  27.     applications.
  28.  
  29.     a  simple (but impressive)    standalone help browser `xmhelp'  is
  30.     included in the libhelp distribution.
  31.  
  32.     an alternative implementation  for  the  libhelp interface  (named
  33.     `libhlpclient')  provides     client-server help.  this    library
  34.     transparently starts and controlls a help server (currently xmhelp
  35.     or NCSA Mosaic(tm)) for the applications help requests.
  36.  
  37. contents
  38. --------
  39.  
  40.     the libhelp distribution contains the following directories
  41.  
  42.     libhelp       - help browser library implementation
  43.     libhlpclient  - library for client-server help
  44.     xmhelp        - sample standalone help browser
  45.  
  46.     libButtFace   - the Button Face library 1.0 by Harald Albrecht
  47.     libXpm        - the X pixmap library by Arnaud Le Hors.
  48.     libhtmlw      - the html widget library from NCSA Mosaic(tm) 2.4
  49.  
  50.     help          - the online help documents and images for libhelp
  51.     pixmaps       - pixmaps used for colored buttons and the icon. 
  52.     emacs         - example emacs lisp code concerning html. 
  53.  
  54.     and files:
  55.  
  56.     History Readme Imakefile Licence 
  57.     
  58. copyright
  59. ---------
  60.  
  61.     copyright (c) 1995 ipvr stuttgart and thomas harrer.
  62.  
  63.     ipvr = institute of parallel and distributed high-performace
  64.     systems. university of stuttgart.
  65.  
  66.     libhelp  needs  3 libraries  (which are shipped  with  the libhelp
  67.     distribution: the HTML widget library,  the ButtonFace library and
  68.     the Xpm library).    see  the file  "Licence" for    licencing and
  69.     copyright details for them.
  70.  
  71.     If you use libhelp and like it, please send a  postcard to us. See
  72.     the online documentation for the postcard address.
  73.  
  74. source
  75. ------
  76.  
  77.     future versions of libhelp can be obtained by anonymous ftp from  
  78.  
  79.       ftp.informatik.uni-stuttgart.de:/pub/libhelp/libhelp-<ver>.tar.gz
  80.  
  81.     where <ver> denotes the version number. 
  82.  
  83.     note: libhelp  will be officially released  in august 95. if there
  84.     is nothing on ftp.informatik.uni-stuttgart.de write me for a copy.
  85.         
  86. platforms
  87. ---------
  88.  
  89.     libhelp   is  known  to   compile on  the  following  platforms  (in
  90.     alphabetical order):
  91.  
  92.     hp    (hp/ux A.09.03 A 9000/730 with c89, x11r5 and motif 1.2)
  93.     ibm   (aix 3.2.5 with cc, ibm x11r5 and motif-1.2).
  94.     pc    (linux 1.x with gcc, x11r5 and motif-1.2).
  95.     sgi   (irix 5.1.x).
  96.     sun 4 (sunos 4.1.x with gcc, x11r5 and motif 1.2).
  97.     sun 5 (solaris 1.2 with gcc, x11r5 and motif 1.2).
  98.  
  99. compilation instructions
  100. ------------------------
  101.  
  102.     libhelp sources  are written in ansi-c.   you  will need a working
  103.     ansi-c compiler (e. g.   gcc) to compile libhelp. libhelp requires
  104.     x11 and osf/motif(tm). we use x11r5 and motif-1.2.  we don't know,
  105.     if it compiles with x11r4 and motif-1.1, but there will be a great
  106.     chance that it will.
  107.  
  108.     in order to compile  libhelp and the standalone helpbrowser xmhelp
  109.     you will need a  working imake.  the  global Imakefile defines the
  110.     variable LIBDIRS to 'libhelp libButtFace  libhtmlw'.  if you don't
  111.     have the xpm library (version 3.4) you will need  to add libXpm to
  112.     LIBDIRS to use the xpm library that is shipped with libhelp.
  113.  
  114.     to build libhelp, type:
  115.  
  116.     xmkmf
  117.         make Makefiles
  118.     make 
  119.     
  120.     if you want to use a different compiler than gcc type 
  121.  
  122.     make CC=<compiler>
  123.  
  124.     in the last step.
  125.  
  126.     you can add additional include dirs in INCS, optimisation flags in
  127.     COPT, additional  libraries  for  your host   in  LIBS  and  other
  128.     makefile definitions in DEFS. for example
  129.  
  130.     make CC=cc LIBS='-lbsd -lregexp' INCS='-I/usr/bsdinclude' \
  131.              COPT='-g' DEFS='-DDEBUG -Wall'
  132.  
  133.     you can hardcode the search path for helpfiles and images with the
  134.     preprocession macro HELP_PATH. per default, it is set to
  135.  
  136.     "/usr/local/help:../help:help:../images:images:."
  137.  
  138.     but you can compile in your local help directories, for example
  139.  
  140.     make DEFS='-DHELP_PATH=\"/usr/help:/usr/images\"'
  141.  
  142.     if  you want `/usr/help'  and `/usr/images'  be  searched for help
  143.     files and images. at runtime, you can add entries to the help path
  144.     via the environment variable LIBHELPPATH.
  145.  
  146.     supposed there are no compilation  errors this results in a single
  147.     executable   file    xmhelp/xmhelp    and   the    library   files
  148.     libhelp/libhelp.a,  libButtFace/libButtFace.a  libhtmlw/libhtmlw.a
  149.     and if choosen libXpm/libXpm.a.
  150.  
  151.     to link libhelp to other applications you  should include the file
  152.     libhelp/help.h into   the  sources. link   the libraries  in   the
  153.     following order:
  154.  
  155.     -lhelp -lButtface -lXpm -lXm -lXmu -lXt -lX11 ...
  156.  
  157.     if  you don't want   the help browser to  be   linked in, you  can
  158.     alternatively use the libhlpclient  library. for more information,
  159.     see the Readme file in the libhlpclient directory.
  160.  
  161. minimum installation
  162. --------------------
  163.  
  164.     in order to have the right icons in the history page, you'll need
  165.     to copy at least the images
  166.  
  167.     icon-history.gif icon-index.gif libhelp-bar.gif
  168.  
  169.     from the help/ directory to a place pointed by the LIBHELPPATH (or
  170.     internal HELP_PATH). To use  the libhelp documentation as part  of
  171.     your help system, you need  to copy all files  ending in .html and
  172.     .gif to such a directory. 
  173.  
  174.     additionally, you can place libhelp.a and help.h in a global place
  175.     where compiler and linker will find them. On my systems, libhelp.a
  176.     is  in /usr/local/lib, help.h   is in /usr/local/include. Also you
  177.     you   might  want to   move  xmhelp to a   directory  in your PATH
  178.     (necessary for using xmhelp as help server).
  179.  
  180.     i use libhelp as a shared  library. for example, my xmhelp browser
  181.     is just about 10 kbytes. if you try to create shared libraries for
  182.     your system,   please send me  information   about it. it   may be
  183.     distributed in further releases.
  184.  
  185. X default resources
  186. -------------------
  187.  
  188.     `xmhelp'  includes a  set of fallback   X  resources that  provide
  189.     reasonable screen display properties for color displays.
  190.  
  191.     the   default resource class   name  for  the  libhelp library  is
  192.     `Libhelp'.   your application  can  override this  class name by a
  193.     interface funtion    (e.g.  giving it  the  class  name   of  your
  194.     application).
  195.  
  196. getting more help
  197. -----------------
  198.  
  199.     libhelp provides a  comprehensive help system. it  offers a set of
  200.     example help files and  images documenting itself. the  help texts
  201.     are written in the html  (hypertext markup language) language.  
  202.  
  203.     the  libhelp-index.html document is  designed  to be added to your
  204.     application as a "help for help" entry. feel free  to add the help
  205.     documents to  your application. (or  contribute if you have better
  206.     ones (e.g. more elaborate english).
  207.  
  208.     if you  have built libhelp   successfully you can view the  online
  209.     help  files  with the  standalone browser  `xmhelp'.  probably you
  210.     need to set the environment  variable LIBHELPPATH to the directory
  211.     "help" in the libhelp distribution.
  212.  
  213.     at any   time (before you've  compiled libhelp  or if  it  was not
  214.     possible  to do so) you can  view the online  help  any www client
  215.     which can  display html files e.g. NCSA  Mosaic(tm). change to the
  216.     directory "help/" and start your www client on the index file
  217.  
  218.     libhelp-index.html.
  219.  
  220. bug reports and comments
  221. ------------------------
  222.  
  223.     bug reports and other comments can be sent to 
  224.     
  225.     mache@informatik.uni-stuttgart.de
  226.  
  227.     if you  find libhelp useful   or particularly interesting,  please
  228.     also send  us  a note.  user  feedback can  be very important  for
  229.     further support and developement of libhelp.
  230.  
  231. --------------
  232.     cheers,
  233.  
  234.         thomas harrer
  235.         Thomas.Harrer@rus.uni-stuttgart.de
  236.  
  237. --- i love gnu emacs: -----------------------------------------
  238. --  local variables:    
  239. --  mode:        text
  240. --  tab-stop-list:    (4 8 12)
  241. --  fill-prefix:    "    "
  242. --  End:
  243.  
  244.  
  245.